feat(samples): add 2D-to-3D Store Locator sample and seamless 2D/3D mode switching across showcase apps - #88

Review: 2D-to-3D Store Locator Sample & Mode Switching

Thank you for putting this together, @LoyalAbbas! The architecture and craftsmanship across this PR are fantastic:

• True 3-Way Parity: Achieving identical feature sets, styling, and kinematics across Kotlin Views, Java Views, and Jetpack Compose is a high benchmark and executed cleanly.
• MVVM Architecture: The domain separation in ApiDemos/common (StoreLocation and StoreLocatorViewModel) providing immutable StateFlow alongside asLiveData() for Java interoperability is well-structured and easy to follow.
• Comprehensive ViewModel Testing: The 8 unit tests in StoreLocatorViewModelTest thoroughly validate filtering, selection, and mode synchronization.

We tested the PR end-to-end on device (including millisecond logcat timing and autonomous UI exploration with Artemis). Here is our feedback and suggested refinements:

1. Map Readiness & 300ms Fallback Delay (SampleBaseActivity & GoogleMap3D)

• Observations: In SampleBaseActivity and GoogleMap3D.kt, the readiness fallback delay was reduced from 2000L to 300L.
• Hardware Test Results: On cold launch testing on a Pixel device, onMap3DViewReady fired followed ~303ms later by onMapReady (via delay(300)). The native googleMap3D.setOnMapReadyListener never fired during the session. The 300ms delay effectively worked around this SDK quirk, and the map surface, pins, and controls loaded cleanly behind the initial loading spinner.
• Recommendation: Because setOnMapReadyListener is largely a no-op or one-shot in play-services-maps3d:16.0.1, please add a brief code comment documenting why the 300ms fallback exists, so future maintainers understand it is an intentional workaround for the native callback.

2. Marker Re-Creation & Selection Performance in Views (StoreLocatorActivity)

• Location: StoreLocatorActivity.kt (lines 281–352) & StoreLocatorActivity.java (lines 321–391)
• The Issue: In syncMapMarkersAndCamera:

  if (currentIds != lastRenderedStoreIds || selectedId != lastRenderedSelectedStoreId)

  This conflates dataset changes (filtering amenities) with selection changes (user tapped a store card or pin).
• Impact: Whenever any store is clicked, rebuildStoreMarkers executes activeMarkers.values.forEach { it.remove() }, clears the map, and invokes map.addMarker(...) for all 8 stores from scratch. Destroying and re-creating 3D extruded pins causes noticeable pin flickering on the map and unnecessary native allocations at the exact moment the camera begins its flyCameraTo animation.
• Recommendation: Separate filtering from selection:
  1. Dataset changes (currentIds != lastRenderedStoreIds): Diff and add/remove only the markers that entered or exited the filtered list.
  2. Selection changes (selectedId != lastRenderedSelectedStoreId): Selectively update only the previously selected marker (reverting scale to 1.0f, zIndex = 1, and blue/gray color) and the newly selected marker (elevating scale to 1.35f, zIndex = 10, and Google Yellow #F4B400). Keep the other 6 markers completely untouched.
  3. Lifecycle: Add onDestroy() overrides in both StoreLocatorActivity classes to explicitly remove activePopover and activeMarkers.

3. Product Identity: Default Mode in PlacesUIKit3D

• Location: PlacesUIKit3D/src/main/java/com/example/placesuikit3d/ui/viewmodel/PlaceSearch3DViewModel.kt
• The Issue: Changing the default launch state of PlacesUIKit3D from 3D Hybrid view to 2D Roadmap (tilt = 0.0).
• Feedback: This module is our flagship showcase for PlacesUIKit3D—demonstrating photorealistic 3D building meshes, orbital camera maneuvers, and 3D pins anchored to building roofs (AltitudeMode.RELATIVE_TO_MESH). Defaulting to a flat 2D roadmap hides the core 3D value proposition on first launch. Having a 2D switch is great, but PlacesUIKit3D should likely remain 3D by default on startup.

4. Duplicate Quick Settings Dialog in PlacesUIKit3D

• Location: PlacesUIKit3D/src/main/java/com/example/placesuikit3d/MainActivity.kt
• Feedback: The PR adds ~180 lines implementing an ad-hoc AlertDialog with RadioButtons and Switches for map modes, color schemes, and camera controls. This duplicates the exact layout and logic of Map3DQuickSettingsWidget (Compose) and Map3DQuickSettingsDialog (Views). Maintaining two parallel copies of settings UI across sample modules creates tech debt when SDK control APIs evolve.

5. Scope & Granularity

• Feedback: This PR touches 56 files across 5 distinct modules (Store Locator across 3 frameworks, 2D/3D mode-switching in 5 existing samples, PlacesUIKit3D feature work, and maps3d-compose library changes). Consider splitting into:
  • PR 1: Canonical Store Locator sample (Kotlin, Java, Compose) and its core dependencies.
  • PR 2: Cross-app 2D/3D mode-switching in existing showcase apps and PlacesUIKit3D.
  • Benefit: Greatly simplifies review, minimizes blast radius, and preserves clean git bisect history.

6. Android Lint & Code Polish

• GitHub Advanced Security / Lint:
  • Maps3DSamples/ApiDemos/common/src/main/res/values/strings.xml:325: Flagged spelling warning for "Drive-Thru". Please add tools:ignore="Spelling" if intentional.
  • Maps3DSamples/ApiDemos/common/src/main/res/values/strings.xml:333: Flagged Potential Plurals for "%1$d of %2$d stores". Please use <plurals> or add tools:ignore="PluralsCandidate".
• Hardcoded Strings:
  • In MainActivity.kt (Kotlin & Compose), text = "2D / ROADMAP" is hardcoded in Compose rather than referencing a string resource.
  • In StoreLocation.kt, StoreAmenity hardcodes English label strings (val label: String) instead of string resource IDs (@StringRes val labelResId: Int).
  • In PlacesRepositoryImpl.kt (line 441), category matching uses inline string regex heuristics (cleaned.contains("coffee"), "park", etc.). It would be cleaner to map standard Places API types (Place.Type) or use a structured enum map.
• Redundant Startup Invocations:
  • In SampleBaseActivity.kt and SampleBaseActivity.java, onSampleEntered(), applyTo(), and googleMap3D.setCamera(initialCamera) are called during onMap3DViewReady and then executed again inside onMapReady. Consolidating these avoids duplicate camera snapping or interrupting flight animations on startup.